Create Branch

The default branch for VStory is the develop branch. Whether it's feature development, bug fixes, or documentation writing, please create a new branch and then merge it into the develop branch. Use the following code to create a branch:

// Create a branch for documentation and demo
git checkout -b docs/add-funnel-demo

Find or Create Issue

In principle, we require that each PR has a corresponding issue. Before starting development, please make sure there is a corresponding issue and the issue has not been claimed.

Search for Demo Issue

You can search for demo-related issues in the following way:

label:demos

Some features may be associated with the doc label, so you can further check if the issue is purely a demo task.

Create Demo Issue

Click on "NEW ISSUE", open the issue selection page, choose "Others".

Fill in the relevant information for the document issue you want to submit, and tag it with the "demos" label.

Claim Issue

If you want to submit a demo or fix a demo bug, you can leave a message under that issue to claim it. The administrator will contact you, confirm, and then assign the issue to you.

For example:

Create or Modify Demo

The location of VStory documents and demos in the project is as follows (examples):

Taking the example document of the bar leap animation as an example (currently one example contains both Chinese and English versions, located in the zh & en paths):

The example Markdown content is divided into several parts:

Metadata: Defines the attributes of the example content, including chart category, cover image, keywords, etc.
Title: The content under the first-level title corresponds to the description of the example.
Key Configurations: Key configuration explanations included in the example, which will be displayed on the right side of the example page under "Key Configurations".
Code Demo: The specific code content executed in the example, currently only supports native JavaScript code.

The metadata fields in Markdown are defined as follows:

group: The category information of the example, describing what chart category the current example belongs to.
title: The title of the example.
keywords: Keywords of the example.
order: The sorting basis of the example under the same group.
cover: The cover image of the example.
tutorial: Link to the tutorial (the default example tutorial will jump to the tutorial corresponding to the example group).

Currently, the group of chart examples contains multiple categories, such as animate, works-show, etc., corresponding to the categories under all charts in the VStory example gallery. You can refer to existing example documents to fill in specific category fields.

After completing the new demo, you can add the demo path and title in the docs/assets/examples/menu.json file:

For image resources needed during the demo creation process, please refer to 6. How to Upload Image chapter.

Use Marscode AI Programming Assistant for Demo Writing

With the help of the Marscode AI Programming Assistant, you can provide comprehensive assistance throughout the document creation process.

If you haven't installed the Marscode AI Programming Assistant yet, please download it from this link: https://www.marscode.cn/home?utm_source=developer&utm_medium=oss&utm_campaign=visactor_a

In demo writing, using the context directive appropriately can improve the accuracy of the content.

**⭐️ #Workspace**

Select global code in Workspace as context, and AI will automatically find relevant code context based on the user query.

**⭐️ #Files**

Search and select files in the code repository as context.

**⭐️ #Code**

Search and select functions or classes in the code repository as context.

Here are examples of how to use the Marscode AI Programming Assistant for demo writing.

5.1 Provide Document Framework

Here by invoking #Workspace, then ask questions, select the content of an example document, and ask it to generate a new example document based on it.

You can continue to make detailed adjustments based on this.

5.2 Generate Text Descriptions

The description text for each demo can be generated first using Marscode, and then proofread and adjusted. For example:

5.3 Generate Example Code

To better explain the principles and usage, it is usually necessary to provide a demo that can be actually run. You can use the code generation capability of Marscode to generate example code for us. However, the code generation capabilities of various AIs cannot guarantee accuracy, so further verification is needed.

5.4 Content Retrieval

Usually, each Q&A in Marscode will provide reference documents, which can provide more context for further analysis.

You can also directly search for files:

Submit Code

After completing the document, push the code to your remote branch. For example:

git commit -a -m "docs: add custom funnel demo and related docs"

VisActor's commit messages follow the Conventional Commits specification, with docs used for demos.

<type>[optional scope]: <description>

Common type values include docs (documentation, log changes), feat (new feature), fix (bug fix), refactor (code refactoring), etc. Please choose according to the actual situation.

Write a brief and precise description in English before committing.

Before submitting the commit, we will perform commit lint checks. You can check the lint rules for details.

A common issue is when the remote upstream (@visactor/vstory) has been updated, which may cause conflicts when submitting the Pull Request. Therefore, before submitting, merge the commits from other developers with your own commits. Switch to the develop branch using the following code: